feat(firewall): download from a random origin with cross-origin fallback - #18

diff --git a/.github/workflows/test-sfw-mirror.yml b/.github/workflows/test-sfw-mirror.yml
new file mode 100644
--- /dev/null
+++ b/.github/workflows/test-sfw-mirror.yml
@@ -1,0 +1,74 @@
+name: 'test: sfw mirror'
+run-name: 'test: sfw mirror'
+
+# Sfw binary download origins can fail, ensure the action still works
+# if only one of them is unavailable
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  fault-download-origin:
+    name: 'Block a download origin (${{ matrix.os }}, ${{ matrix.blocked }})'
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-2025, ubuntu-26.04]
+        # Each origin must carry the install alone. The github case only
+        # passes with the mirror fallback in the checked-out action.
+        blocked: [github, mirror]
+    steps:
+      - name: 'Bootstrap checkout'
+        shell: bash
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          SERVER_URL: ${{ github.server_url }}
+          REPOSITORY: ${{ github.repository }}
+          TRIGGER_REF: ${{ github.sha }}
+        run: |
+          set -euo pipefail
+          git init -q
+          git config --local advice.detachedHead false
+          git remote add origin "${SERVER_URL}/${REPOSITORY}"
+          AUTH_B64="$(printf 'x-access-token:%s' "${GITHUB_TOKEN}" | base64 | tr -d '\n')"
+          export GIT_CONFIG_COUNT=1
+          export GIT_CONFIG_KEY_0="http.${SERVER_URL}/.extraheader"
+          export GIT_CONFIG_VALUE_0="AUTHORIZATION: basic ${AUTH_B64}"
+          git fetch --no-tags --prune --depth 1 origin "${TRIGGER_REF}"
+          git checkout -q --detach FETCH_HEAD
+      - name: 'Block the origin in the hosts file'
+        shell: bash
+        env:
+          BLOCKED: ${{ matrix.blocked }}
+          RUNNER_OS: ${{ runner.os }}
+        run: |
+          set -euo pipefail
+          if [ "$RUNNER_OS" = Windows ]; then HOSTS="$WINDIR/System32/drivers/etc/hosts"; else HOSTS=/etc/hosts; fi
+          if [ "$BLOCKED" = github ]; then
+            hosts="github.com objects.githubusercontent.com release-assets.githubusercontent.com"
+          else
+            hosts="install.socket.dev"
+          fi
+          # 127.0.0.1 refuses the connection at once. A black-hole address would
+          # make every attempt wait out a TCP connect timeout, which on Linux
+          # outlives the job.
+          for h in $hosts; do printf '127.0.0.1 %s\n' "$h" | sudo tee -a "$HOSTS" > /dev/null 2>&1 || printf '127.0.0.1 %s\n' "$h" >> "$HOSTS"; done
+          [ "$RUNNER_OS" = Windows ] && ipconfig //flushdns > /dev/null || true
+      - name: 'Install socket firewall via the remaining origin'
+        uses: ./
+        with:
+          mode: firewall
+          job-summary: errors
+          use-cache: 'false'
+      - name: 'Run the installed binary'
+        shell: bash
+        run: sfw --version

diff --git a/dist/main.js b/dist/main.js
--- a/dist/main.js
+++ b/dist/main.js
@@ -22135,6 +22135,12 @@
 */
 const DOWNLOAD_RETRY_DELAYS_SECONDS = [30, 60];
 /**
+* Socket-owned mirror of the sfw-free release binaries, relayed by
+* firewall-download-server in depscan. Free edition only: the enterprise
+* repository is private and not mirrored.
+*/
+const FIREWALL_FREE_MIRROR_BASE_URL = "https://install.socket.dev/firewall/dl";
+/**
 * Name the firewall binary is cached and executed under.
 */
 const FIREWALL_EXEC_NAME = "sfw";
@@ -22163,14 +22169,15 @@
 		versionToDownload,
 		process.arch
 	];
-	const url = `https://github.com/SocketDev/${repo}/releases/download/${versionToDownload}/${nameDownload}`;
+	const origins = firewallDownloadUrls(edition, repo, versionToDownload, nameDownload);
+	const urls = shuffledIndexes(origins.length).map((i) => origins[i]);
 	let pathCache;
 	if (inputs.useCache) pathCache = find(...cacheOptions);
 	if (!pathCache) {
-		debug(`downloading Socket Firewall binary from: ${url}`);
+		debug(`downloading Socket Firewall binary from: ${urls.join(", ")}`);
 		let pathDownload;
 		try {
-			pathDownload = await downloadToolWithRetry(url);
+			pathDownload = await downloadToolWithRetry(urls);
 		} catch (error) {
 			throw new Error(`Failed to download Socket Firewall binary: ${(0, import_message.errorMessage)(error)}`);
 		}
@@ -22196,26 +22203,61 @@
 	}
 }
 /**
-* `downloadTool` with attempts layered on top of its own. The last error is
-* rethrown untouched so the caller still reports the real cause.
+* `downloadTool` with attempts layered on top of its own, alternating between
+* equivalent origins. Retryable failures spend the delay table; an error that
+* a retry cannot change (a 404) still gets one immediate try per remaining
+* origin, because a missing asset on one host says nothing about the others.
+* The last error is rethrown untouched so the caller still reports the real
+* cause.
 *
-* @param {string} url Asset to download.
+* @param {string[]} urls Equivalent origins for the same asset, in the order
+*   to try them.
 *
 * @returns {Promise<string>} Path the asset was downloaded to.
 */
-async function downloadToolWithRetry(url) {
+async function downloadToolWithRetry(urls) {
 	let lastError;
-	for (let attempt = 0; attempt <= DOWNLOAD_RETRY_DELAYS_SECONDS.length; attempt += 1) try {
-		return await downloadTool(url);
-	} catch (error) {
-		lastError = error;
-		const seconds = DOWNLOAD_RETRY_DELAYS_SECONDS[attempt];
-		if (seconds === void 0 || !isRetryableDownloadError(error)) break;
-		warning(`Socket Firewall binary download failed (attempt ${attempt + 1} of ${DOWNLOAD_RETRY_DELAYS_SECONDS.length + 1}): ${(0, import_message.errorMessage)(error)}. Retrying in ${seconds}s.`);
-		await setTimeout$1(seconds * 1e3);
+	const remaining = urls.slice();
+	let attempt = 0;
+	while (remaining.length > 0) {
+		const url = remaining[attempt % remaining.length];
+		try {
+			return await downloadTool(url);
+		} catch (error) {
+			lastError = error;
+			if (!isRetryableDownloadError(error)) {
+				remaining.splice(remaining.indexOf(url), 1);
+				if (remaining.length === 0) break;
+				warning(`Socket Firewall binary download from ${url} failed: ${(0, import_message.errorMessage)(error)}. Trying ${remaining[attempt % remaining.length]}.`);
+				continue;
+			}
+			const seconds = DOWNLOAD_RETRY_DELAYS_SECONDS[attempt];
+			if (seconds === void 0) break;
+			warning(`Socket Firewall binary download from ${url} failed (attempt ${attempt + 1} of ${DOWNLOAD_RETRY_DELAYS_SECONDS.length + 1}): ${(0, import_message.errorMessage)(error)}. Retrying in ${seconds}s.`);
+			await setTimeout$1(seconds * 1e3);
+			attempt += 1;
+		}
 	}
 	throw lastError;
 }
+/**
+* Equivalent origins to download one release asset from. GitHub release
+* assets come first; the free edition is also mirrored on Socket-owned
+* infrastructure. The enterprise repository is private and not mirrored, so it
+* stays GitHub-only. Callers decide the order to try them in.
+*
+* @param {string} edition Firewall edition being installed.
+* @param {string} repo GitHub repository the release lives in.
+* @param {string} version Release tag to download.
+* @param {string} asset Release asset name.
+*
+* @returns {string[]} Download URLs, GitHub first.
+*/
+function firewallDownloadUrls(edition, repo, version, asset) {
+	const urls = [`https://github.com/SocketDev/${repo}/releases/download/${version}/${asset}`];
+	if (edition === "free") urls.push(`${FIREWALL_FREE_MIRROR_BASE_URL}/${version}/${asset}`);
+	return urls;
+}
 function firewallReleaseVersion(requestedVersion) {
 	let versionToDownload = FIREWALL_VERSION;
 	if (requestedVersion && requestedVersion !== "latest") {
@@ -22254,6 +22296,25 @@
 	return status >= 500 || status === 408 || status === 429;
 }
 /**
+* A random permutation of `0 .. length - 1` (Fisher-Yates), for callers that
+* need to try equivalent options in an unbiased order.
+*
+* @param {number} length How many indexes to permute.
+* @param {() => number} random Injectable for tests.
+*
+* @returns {number[]} Every index once, in random order.
+*/
+function shuffledIndexes(length, random = Math.random) {
+	const order = Array.from({ length }, (_, i) => i);
+	for (let i = order.length - 1; i > 0; i--) {
+		const j = Math.floor(random() * (i + 1));
+		const swap = order[i];
+		order[i] = order[j];
+		order[j] = swap;
+	}
+	return order;
+}
+/**
 * Compare a downloaded binary against the hash pinned for its release and
 * throw when they differ. Both hashes are printed so an operator can tell a
 * stale pin apart from a tampered download.

diff --git a/src/tools/firewall.js b/src/tools/firewall.js
--- a/src/tools/firewall.js
+++ b/src/tools/firewall.js
@@ -88,6 +88,14 @@
 export const DOWNLOAD_RETRY_DELAYS_SECONDS = [30, 60]
 
 /**
+ * Socket-owned mirror of the sfw-free release binaries, relayed by
+ * firewall-download-server in depscan. Free edition only: the enterprise
+ * repository is private and not mirrored.
+ */
+export const FIREWALL_FREE_MIRROR_BASE_URL =
+  'https://install.socket.dev/firewall/dl'
+
+/**
  * Name the firewall binary is cached and executed under.
  */
 export const FIREWALL_EXEC_NAME = 'sfw'
@@ -147,8 +155,16 @@
     process.arch,
   ]
 
-  // construct the download url
-  const url = `https://github.com/SocketDev/${repo}/releases/download/${versionToDownload}/${nameDownload}`
+  // construct the download urls, tried in a random order per job: half the
+  // fleet's downloads keep the mirror's edge cache warm, which is what lets it
+  // keep serving during a GitHub release-asset incident.
+  const origins = firewallDownloadUrls(
+    edition,
+    repo,
+    versionToDownload,
+    nameDownload,
+  )
+  const urls = shuffledIndexes(origins.length).map(i => origins[i])
 
   let pathCache
 
@@ -159,13 +175,13 @@
 
   // no cache, download new
   if (!pathCache) {
-    debug(`downloading Socket Firewall binary from: ${url}`)
+    debug(`downloading Socket Firewall binary from: ${urls.join(', ')}`)
 
     let pathDownload
 
     try {
       // download it
-      pathDownload = await downloadToolWithRetry(url)
+      pathDownload = await downloadToolWithRetry(urls)
     } catch (error) {
       throw new Error(
         `Failed to download Socket Firewall binary: ${errorMessage(error)}`,
@@ -228,43 +244,84 @@
 }
 
 /**
- * `downloadTool` with attempts layered on top of its own. The last error is
- * rethrown untouched so the caller still reports the real cause.
+ * `downloadTool` with attempts layered on top of its own, alternating between
+ * equivalent origins. Retryable failures spend the delay table; an error that
+ * a retry cannot change (a 404) still gets one immediate try per remaining
+ * origin, because a missing asset on one host says nothing about the others.
+ * The last error is rethrown untouched so the caller still reports the real
+ * cause.
  *
- * @param {string} url Asset to download.
+ * @param {string[]} urls Equivalent origins for the same asset, in the order
+ *   to try them.
  *
  * @returns {Promise<string>} Path the asset was downloaded to.
  */
-export async function downloadToolWithRetry(url) {
+export async function downloadToolWithRetry(urls) {
   let lastError
+  const remaining = urls.slice()
+  let attempt = 0
 
-  for (
-    let attempt = 0;
-    attempt <= DOWNLOAD_RETRY_DELAYS_SECONDS.length;
-    attempt += 1
-  ) {
+  while (remaining.length > 0) {
+    const url = remaining[attempt % remaining.length]
+
     try {
       return await downloadTool(url)
     } catch (error) {
       lastError = error
 
+      if (!isRetryableDownloadError(error)) {
+        remaining.splice(remaining.indexOf(url), 1)
+        if (remaining.length === 0) {
+          break
+        }
+        warning(
+          `Socket Firewall binary download from ${url} failed: ${errorMessage(error)}. Trying ${remaining[attempt % remaining.length]}.`,
+        )
+        continue
+      }
+
       const seconds = DOWNLOAD_RETRY_DELAYS_SECONDS[attempt]
 
-      if (seconds === undefined || !isRetryableDownloadError(error)) {
+      if (seconds === undefined) {
         break
       }
 
       warning(
-        `Socket Firewall binary download failed (attempt ${attempt + 1} of ${DOWNLOAD_RETRY_DELAYS_SECONDS.length + 1}): ${errorMessage(error)}. Retrying in ${seconds}s.`,
+        `Socket Firewall binary download from ${url} failed (attempt ${attempt + 1} of ${DOWNLOAD_RETRY_DELAYS_SECONDS.length + 1}): ${errorMessage(error)}. Retrying in ${seconds}s.`,
       )
-
       await setTimeout(seconds * 1000)
+      attempt += 1
     }
   }
 
   throw lastError
 }
 
+/**
+ * Equivalent origins to download one release asset from. GitHub release
+ * assets come first; the free edition is also mirrored on Socket-owned
+ * infrastructure. The enterprise repository is private and not mirrored, so it
+ * stays GitHub-only. Callers decide the order to try them in.
+ *
+ * @param {string} edition Firewall edition being installed.
+ * @param {string} repo GitHub repository the release lives in.
+ * @param {string} version Release tag to download.
+ * @param {string} asset Release asset name.
+ *
+ * @returns {string[]} Download URLs, GitHub first.
+ */
+export function firewallDownloadUrls(edition, repo, version, asset) {
+  const urls = [
+    `https://github.com/SocketDev/${repo}/releases/download/${version}/${asset}`,
+  ]
+
+  if (edition === 'free') {
+    urls.push(`${FIREWALL_FREE_MIRROR_BASE_URL}/${version}/${asset}`)
+  }
+
+  return urls
+}
+
 export function firewallReleaseVersion(requestedVersion) {
   let versionToDownload = FIREWALL_VERSION
 
@@ -316,6 +373,26 @@
 }
 
 /**
+ * A random permutation of `0 .. length - 1` (Fisher-Yates), for callers that
+ * need to try equivalent options in an unbiased order.
+ *
+ * @param {number} length How many indexes to permute.
+ * @param {() => number} random Injectable for tests.
+ *
+ * @returns {number[]} Every index once, in random order.
+ */
+export function shuffledIndexes(length, random = Math.random) {
+  const order = Array.from({ length }, (_, i) => i)
+  for (let i = order.length - 1; i > 0; i--) {
+    const j = Math.floor(random() * (i + 1))
+    const swap = order[i]
+    order[i] = order[j]
+    order[j] = swap
+  }
+  return order
+}
+
+/**
  * Compare a downloaded binary against the hash pinned for its release and
  * throw when they differ. Both hashes are printed so an operator can tell a
  * stale pin apart from a tampered download.

diff --git a/test/unit/tools/firewall.test.mts b/test/unit/tools/firewall.test.mts
--- a/test/unit/tools/firewall.test.mts
+++ b/test/unit/tools/firewall.test.mts
@@ -13,7 +13,9 @@
   downloadToolWithRetry,
   FIREWALL_DISTRIBUTIONS,
   FIREWALL_EXEC_NAME,
+  firewallDownloadUrls,
   isRetryableDownloadError,
+  shuffledIndexes,
 } from '../../../src/tools/firewall.js'
 
 const { mockDownloadTool, sleepDelays } = vi.hoisted(() => ({
@@ -147,14 +149,15 @@
 })
 
 describe('downloadToolWithRetry', () => {
+  const GITHUB = 'https://github.test/sfw'
+  const MIRROR = 'https://mirror.test/sfw'
+
   it('returns the path once an attempt succeeds', async () => {
     mockDownloadTool
       .mockRejectedValueOnce(httpError(504))
       .mockResolvedValueOnce('/tmp/sfw')
 
-    await expect(
-      downloadToolWithRetry('https://example.test/sfw'),
-    ).resolves.toBe('/tmp/sfw')
+    await expect(downloadToolWithRetry([GITHUB])).resolves.toBe('/tmp/sfw')
     expect(mockDownloadTool).toHaveBeenCalledTimes(2)
     expect(sleepDelays).toEqual([30_000])
   })
@@ -162,9 +165,9 @@
   it('rethrows the last error after exhausting its attempts', async () => {
     mockDownloadTool.mockRejectedValue(httpError(504))
 
-    await expect(
-      downloadToolWithRetry('https://example.test/sfw'),
-    ).rejects.toThrow('Unexpected HTTP response: 504')
+    await expect(downloadToolWithRetry([GITHUB])).rejects.toThrow(
+      'Unexpected HTTP response: 504',
+    )
     expect(mockDownloadTool).toHaveBeenCalledTimes(3)
     expect(sleepDelays).toEqual([30_000, 60_000])
   })
@@ -172,10 +175,147 @@
   it('does not spend attempts on a missing asset', async () => {
     mockDownloadTool.mockRejectedValue(httpError(404))
 
-    await expect(
-      downloadToolWithRetry('https://example.test/sfw'),
-    ).rejects.toThrow('Unexpected HTTP response: 404')
+    await expect(downloadToolWithRetry([GITHUB])).rejects.toThrow(
+      'Unexpected HTTP response: 404',
+    )
     expect(mockDownloadTool).toHaveBeenCalledTimes(1)
     expect(sleepDelays).toEqual([])
   })
+
+  it('alternates origins across the retry schedule', async () => {
+    mockDownloadTool.mockRejectedValue(httpError(504))
+
+    await expect(downloadToolWithRetry([MIRROR, GITHUB])).rejects.toThrow(
+      'Unexpected HTTP response: 504',
+    )
+    expect(mockDownloadTool.mock.calls).toEqual([[MIRROR], [GITHUB], [MIRROR]])
+    expect(sleepDelays).toEqual([30_000, 60_000])
+  })
+
+  it('tries the other origin immediately when a retry cannot help', async () => {
+    // A 404 from the mirror says nothing about GitHub: no backoff, one
+    // immediate try of the other origin.
+    mockDownloadTool
+      .mockRejectedValueOnce(httpError(404))
+      .mockResolvedValueOnce('/tmp/sfw')
+
+    await expect(downloadToolWithRetry([MIRROR, GITHUB])).resolves.toBe(
+      '/tmp/sfw',
+    )
+    expect(mockDownloadTool.mock.calls).toEqual([[MIRROR], [GITHUB]])
+    expect(sleepDelays).toEqual([])
+  })
+
+  it('gives up once every origin reported a missing asset', async () => {
+    mockDownloadTool.mockRejectedValue(httpError(404))
+
+    await expect(downloadToolWithRetry([MIRROR, GITHUB])).rejects.toThrow(
+      'Unexpected HTTP response: 404',
+    )
+    expect(mockDownloadTool).toHaveBeenCalledTimes(2)
+    expect(sleepDelays).toEqual([])
+  })
+
+  it('keeps the healthy origin on the delay table after a miss', async () => {
+    mockDownloadTool
+      .mockRejectedValueOnce(httpError(504))
+      .mockRejectedValueOnce(httpError(404))
+      .mockResolvedValueOnce('/tmp/sfw')
+
+    await expect(downloadToolWithRetry([GITHUB, MIRROR])).resolves.toBe(
+      '/tmp/sfw',
+    )
+    expect(mockDownloadTool.mock.calls).toEqual([[GITHUB], [MIRROR], [GITHUB]])
+    expect(sleepDelays).toEqual([30_000])
+  })
+
+  it('does not spend the delay table on a miss before a flaky origin', async () => {
+    mockDownloadTool
+      .mockRejectedValueOnce(httpError(404))
+      .mockRejectedValue(httpError(504))
+
+    await expect(downloadToolWithRetry([MIRROR, GITHUB])).rejects.toThrow(
+      'Unexpected HTTP response: 504',
+    )
+    expect(mockDownloadTool.mock.calls).toEqual([
+      [MIRROR],
+      [GITHUB],
+      [GITHUB],
+      [GITHUB],
+    ])
+    expect(sleepDelays).toEqual([30_000, 60_000])
+  })
+
+  it('rethrows the flaky origin after a later miss burns no retries', async () => {
+    mockDownloadTool
+      .mockRejectedValueOnce(httpError(504))
+      .mockRejectedValueOnce(httpError(404))
+      .mockRejectedValue(httpError(504))
+
+    await expect(downloadToolWithRetry([GITHUB, MIRROR])).rejects.toThrow(
+      'Unexpected HTTP response: 504',
+    )
+    expect(mockDownloadTool.mock.calls).toEqual([
+      [GITHUB],
+      [MIRROR],
+      [GITHUB],
+      [GITHUB],
+    ])
+    expect(sleepDelays).toEqual([30_000, 60_000])
+  })
 })
+
+describe('firewallDownloadUrls', () => {
+  it('gives the free edition both origins, GitHub first', () => {
+    expect(
+      firewallDownloadUrls(
+        'free',
+        'sfw-free',
+        'v1.15.2',
+        'sfw-free-linux-x86_64',
+      ),
+    ).toEqual([
+      'https://github.com/SocketDev/sfw-free/releases/download/v1.15.2/sfw-free-linux-x86_64',
+      'https://install.socket.dev/firewall/dl/v1.15.2/sfw-free-linux-x86_64',
+    ])
+  })
+
+  it('keeps the enterprise edition GitHub-only', () => {
+    expect(
+      firewallDownloadUrls(
+        'enterprise',
+        'firewall-release',
+        'v1.15.2',
+        'sfw-windows-x86_64.exe',
+      ),
+    ).toEqual([
+      'https://github.com/SocketDev/firewall-release/releases/download/v1.15.2/sfw-windows-x86_64.exe',
+    ])
+  })
+})
+
+describe('shuffledIndexes', () => {
+  it('permutes two indexes by the coin flip', () => {
+    expect(shuffledIndexes(2, () => 0.9)).toEqual([0, 1])
+    expect(shuffledIndexes(2, () => 0.1)).toEqual([1, 0])
+  })
+
+  it('permutes three indexes from the injected sequence', () => {
+    const draws = [0.9, 0.1]
+    expect(shuffledIndexes(3, () => draws.shift() ?? 0)).toEqual([1, 0, 2])
+  })
+
+  it('returns every index exactly once', () => {
+    for (let n = 0; n <= 5; n++) {
+      expect(shuffledIndexes(n).toSorted((a, b) => a - b)).toEqual(
+        Array.from({ length: n }, (_, i) => i),
+      )
+    }
+  })
+
+  it('does not consult the random source for a single index', () => {
+    const random = vi.fn(() => 0.1)
+    expect(shuffledIndexes(1, random)).toEqual([0])
+    expect(random).not.toHaveBeenCalled()
+  })
+})